.TH std::ranges::replace,std::ranges::replace_if 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::ranges::replace,std::ranges::replace_if \- std::ranges::replace,std::ranges::replace_if

.SH Synopsis
   Defined in header <algorithm>
   Call signature
   template< std::input_iterator I,
   std::sentinel_for<I> S,

             class T1, class T2, class Proj =
   std::identity >
   requires std::indirectly_writable<I, const T2&>          (since
   &&                                                       C++20)
            std::indirect_binary_predicate                  (until
                <ranges::equal_to,                          C++26)
   std::projected<I, Proj>, const T1*>
   constexpr I replace( I first, S last, const T1&
   old_value,

                        const T2& new_value, Proj
   proj = {} );
   template< std::input_iterator I,
   std::sentinel_for<I> S,

             class Proj = std::identity,
             class T1 = std::projected_value_t<I,
   Proj>, class T2 = T1 >
   requires std::indirectly_writable<I, const T2&>
   &&                                                       (since
            std::indirect_binary_predicate                  C++26)
                <ranges::equal_to,
   std::projected<I, Proj>, const T1*>
   constexpr I replace( I first, S last, const T1&
   old_value,

                        const T2& new_value, Proj
   proj = {} );
   template< ranges::input_range R,

             class T1, class T2, class Proj =
   std::identity >
   requires
   std::indirectly_writable<ranges::iterator_t<R>,
   const T2&> &&                                                   (since
            std::indirect_binary_predicate                         C++20)
                <ranges::equal_to,                                 (until
                                                                   C++26)
   std::projected<ranges::iterator_t<R>, Proj>,
   const T1*>
   constexpr ranges::borrowed_iterator_t<R>
       replace( R&& r, const T1& old_value,

                const T2& new_value, Proj proj = {}
   );
   template< ranges::input_range R,

             class Proj = std::identity,
             class T1 =
   std::projected_value_t<ranges::iterator_t<R>,
   Proj>,
             class T2 = T1 >
   requires
   std::indirectly_writable<ranges::iterator_t<R>,
   const T2&> &&                                                   (since
            std::indirect_binary_predicate                         C++26)
                <ranges::equal_to,

   std::projected<ranges::iterator_t<R>, Proj>,
   const T1*>
   constexpr ranges::borrowed_iterator_t<R>         \fB(1)\fP
       replace( R&& r, const T1& old_value,

                const T2& new_value, Proj proj = {}
   );
   template< std::input_iterator I,
   std::sentinel_for<I> S,

             class T, class Proj = std::identity,
                                                                          (since
   std::indirect_unary_predicate<std::projected<I,                        C++20)
   Proj>> Pred >                                                          (until
   requires std::indirectly_writable<I, const T&>                         C++26)
   constexpr I replace_if( I first, S last, Pred
   pred,
                                                        \fB(2)\fP
                           const T& new_value, Proj
   proj = {} );
   template< std::input_iterator I,
   std::sentinel_for<I> S,

             class Proj = std::identity,
             class T = std::projected_value_t<I,
   Proj>,
                                                                          (since
   std::indirect_unary_predicate<std::projected<I,                        C++26)
   Proj>> Pred >
   requires std::indirectly_writable<I, const T&>
   constexpr I replace_if( I first, S last, Pred
   pred,

                           const T& new_value, Proj
   proj = {} );
   template< ranges::input_range R, class T, class
   Proj = std::identity,                                    \fB(3)\fP

             std::indirect_unary_predicate<

   std::projected<ranges::iterator_t<R>, Proj>>                                  (since
   Pred >                                                                        C++20)
   requires                                                                      (until
   std::indirectly_writable<ranges::iterator_t<R>,                               C++26)
   const T&>
   constexpr ranges::borrowed_iterator_t<R>

       replace_if( R&& r, Pred pred, const T&
   new_value, Proj proj = {} );
   template< ranges::input_range R, class Proj =
   std::identity,                                                  \fB(4)\fP

             class T =
   std::projected_value_t<ranges::iterator_t<R>,
   Proj>,
             std::indirect_unary_predicate<
                                                                                 (since
   std::projected<ranges::iterator_t<R>, Proj>>                                  C++26)
   Pred >
   requires
   std::indirectly_writable<ranges::iterator_t<R>,
   const T&>
   constexpr ranges::borrowed_iterator_t<R>

       replace_if( R&& r, Pred pred, const T&
   new_value, Proj proj = {} );

   Replaces all elements satisfying specific criteria with new_value in the range
   [first, last).

   1) Replaces all elements that are equal to old_value, using std::invoke(proj, *i) ==
   old_value to compare.
   3) Replaces all elements for which the predicate pred evaluates to true, where
   evaluating expression is std::invoke(pred, std::invoke(proj, *i)).
   2,4) Same as (1,3), but uses r as the range, as if using ranges::begin(r) as first
   and ranges::end(r) as last.

   The function-like entities described on this page are niebloids, that is:

     * Explicit template argument lists cannot be specified when calling any of them.
     * None of them are visible to argument-dependent lookup.
     * When any of them are found by normal unqualified lookup as the name to the left
       of the function-call operator, argument-dependent lookup is inhibited.

   In practice, they may be implemented as function objects, or with special compiler
   extensions.

.SH Parameters

   first, last - the range of elements to process
   r           - the range of elements to process
   old_value   - the value of elements to replace
   new_value   - the value to use as a replacement
   pred        - predicate to apply to the projected elements
   proj        - projection to apply to the elements

.SH Return value

   An iterator equal to last.

.SH Complexity

   Exactly ranges::distance(first, last) applications of the corresponding predicate
   comp and any projection proj.

.SH Notes

   Because the algorithm takes old_value and new_value by reference, it may have
   unexpected behavior if either is a reference to an element of the range
   [first, last).

             Feature-test macro           Value    Std              Feature
   __cpp_lib_algorithm_default_value_type 202403 (C++26) List-initialization for
                                                         algorithms (1-4)

.SH Possible implementation

                                           replace
   struct replace_fn
   {
       template<std::input_iterator I, std::sentinel_for<I> S, class Proj = std::identity,
                class T1 = std::projected_value_t<I, Proj>, class T2 = T1>
       requires std::indirectly_writable<I, const T2&> &&
                std::indirect_binary_predicate
                    <ranges::equal_to, std::projected<I, Proj>, const T1*>
       constexpr I operator()(I first, S last, const T1& old_value,
                              const T2& new_value, Proj proj = {}) const
       {
           for (; first != last; ++first)
               if (old_value == std::invoke(proj, *first))
                   *first = new_value;
           return first;
       }

       template<ranges::input_range R, class Proj = std::identity
                class T1 = std::projected_value_t<ranges::iterator_t<R>, Proj>,
                class T2 = T1>
       requires std::indirectly_writable<ranges::iterator_t<R>, const T2&> &&
                std::indirect_binary_predicate<ranges::equal_to,
                std::projected<ranges::iterator_t<R>, Proj>, const T1*>
       constexpr ranges::borrowed_iterator_t<R>
           operator()(R&& r, const T1& old_value,
                      const T2& new_value, Proj proj = {}) const
       {
           return (*this)(ranges::begin(r), ranges::end(r), old_value,
                          new_value, std::move(proj));
       }
   };

   inline constexpr replace_fn replace {};
                                         replace_if
   struct replace_if_fn
   {
       template<std::input_iterator I, std::sentinel_for<I> S,
                class Proj = std::identity, class T = std::projected_value_t<I, Proj>,
                std::indirect_unary_predicate<std::projected<I, Proj>> Pred>
       requires std::indirectly_writable<I, const T&>
       constexpr I operator()(I first, S last, Pred pred,
                              const T& new_value, Proj proj = {}) const
       {
           for (; first != last; ++first)
               if (!!std::invoke(pred, std::invoke(proj, *first)))
                   *first = new_value;
           return std::move(first);
       }

       template<ranges::input_range R, class Proj = std::identity,
                class T = std::projected_value_t<ranges::iterator_t<R>, Proj>
                std::indirect_unary_predicate
                    <std::projected<ranges::iterator_t<R>, Proj>> Pred>
       requires std::indirectly_writable<ranges::iterator_t<R>, const T&>
       constexpr ranges::borrowed_iterator_t<R>
           operator()(R&& r, Pred pred, const T& new_value, Proj proj = {}) const
       {
           return (*this)(ranges::begin(r), ranges::end(r), std::move(pred),
                          new_value, std::move(proj));
       }
   };

   inline constexpr replace_if_fn replace_if {};

.SH Example


// Run this code

 #include <algorithm>
 #include <array>
 #include <complex>
 #include <iostream>

 void println(const auto& v)
 {
     for (const auto& e : v)
         std::cout << e << ' ';
     std::cout << '\\n';
 }

 int main()
 {
     namespace ranges = std::ranges;

     std::array p{1, 6, 1, 6, 1, 6};
     println(p);
     ranges::replace(p, 6, 9);
     println(p);

     std::array q{1, 2, 3, 6, 7, 8, 4, 5};
     println(q);
     ranges::replace_if(q, [](int x) { return 5 < x; }, 5);
     println(q);

     std::array<std::complex<double>, 2> nums{{{1, 3}, {1, 3}}};
     println(nums);
     #ifdef __cpp_lib_algorithm_default_value_type
         ranges::replace(nums, {1, 3}, {4, 2});
     #else
         ranges::replace(nums, std::complex<double>{1, 3}, std::complex<double>{4, 2});
     #endif
     println(nums);
 }

.SH Output:

 1 6 1 6 1 6
 1 9 1 9 1 9
 1 2 3 6 7 8 4 5
 1 2 3 5 5 5 4 5
 (1,3) (1,3)
 (4,2) (4,2)

.SH See also

   ranges::replace_copy    copies a range, replacing elements satisfying specific
   ranges::replace_copy_if criteria with another value
   (C++20)                 (niebloid)
   (C++20)
   replace                 replaces all values satisfying specific criteria with
   replace_if              another value
                           \fI(function template)\fP
